<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
	<TITLE>Readme for event example</TITLE>
	<META NAME="GENERATOR" CONTENT="OpenOffice.org 2.0  (Linux)">
	<META NAME="CREATED" CONTENT="20061227;17353000">
	<META NAME="CHANGEDBY" CONTENT="kejin">
	<META NAME="CHANGED" CONTENT="20070523;21542600">
	<STYLE TYPE="text/css">
	<!--
		@page { size: 8.5in 11in }
		P { color: #000000 }
		H2 { color: #000000 }
		H3 { color: #000000 }
		PRE { color: #000000 }
		A:link { color: #0000ff }
		A:visited { color: #990066 }
	-->
	</STYLE>
</HEAD>
<BODY LANG="en-US" TEXT="#000000" LINK="#0000ff" VLINK="#990066" BGCOLOR="#ffffff" DIR="LTR">
<H2>PocoCapsule/C++ CORBA example: DDS 
</H2>
<P>Copyright(c) 2006, 2007 by <A HREF="http://www.pocomatic.com/">Pocomatic
Software</A>. All rights reserved.</P>
<P>Developing and deploying DDS applications in traditional
programmatic approach imposes significant challenges to most CORBA
professionals. It requires a considerable learning curve for a
CORBA expert to be able to develop/deploy decent DDS applications. With PocoCapsule/CORBA+DDS,
developing and deploying a DDS application become straightforward
even for CORBA novice. Application developers no longer need to
learn and deal with many system level plumbing details of
DDS, and can focus on solving their own domain issues with DDS.</P>
<P>The development and deployment procedure of a POCO+DDS application
is roughly as follows:</P>
<OL>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=3><I><B>Declaring or
	generating DDS type implementations.</B> </I></FONT>
	</P>
	<P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>This is DDS
	implementations dependent. Some DDS implementations use script tools
	to generate DDS type implementations, and others may simply use
	macros. Developers should check and follow the user documents of
	their chosen DDSs. </I></FONT>
	</P>
	<P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>For convenience of
	playing this example right out-of-the-box, this example comes with a
	functionality simplified and limited implementation of DDS inside
	the </I><A HREF="pocodds"><I><FONT SIZE=2>pocodds</FONT></I></A>
	<I><FONT SIZE=2>sub-directory. By this demo DDS, DDS types (IDL
	structs) and their implementations are declared using macros (and
	therefore, will be automatically generated by IDL and C++
	pre-compiler) as follows: </FONT></I></FONT>
	</P>
</OL>
<UL>
	<UL>
		<LI><P STYLE="margin-bottom: 0in"><I><FONT SIZE=2>use the
		DDS_TYPE() macro in IDL file(s) to declare an IDL struct(s) as a
		DDS type(s) (see example </FONT></I><A HREF="MyDataTypeDefs.idl"><I><FONT SIZE=2>MyDataTypeDefs.idl</FONT></I></A><I><FONT SIZE=2>).
		The IDL header file typesupport.idl in the demo DDS should be
		included in the IDL file(s) to use this macro.</FONT></I></P>
		<LI><P STYLE="margin-bottom: 0in"><I><FONT SIZE=2>use the
		DDS_TYPE() macro in C++ header files to declare a DDS type's
		implementation (see example </FONT></I><A HREF="MyDataTypeImpls.h"><I><FONT SIZE=2>MyDataTypeImpls.h</FONT></I></A><I><FONT SIZE=2>).
		The C++ header file typesupport.h in the demo DDS should be
		included in the header file(s) to use this macro.</FONT></I></P>
	</UL>
</UL>
<OL START=2>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=3><I><B>Implementing
	emitters and listeners, which perform DDS data writings and
	readings</B><FONT SIZE=2>. </FONT></I></FONT>
	</P>
	<P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>These implementation
	assumes DDS DataWriter and DataReader references will be injected to
	them by PocoCapsule container and/or the underlying DDS engine.</I></FONT></P>
</OL>
<UL>
	<UL>
		<LI><P STYLE="margin-bottom: 0in"><I><FONT SIZE=2>The emitter beans
		can be any class, having public methods for container to inject a
		DDS data reader reference (see example <A HREF="EmitterImpl.h">EmitterImpl.h</A>
		and <A HREF="EmitterImpl.C">EmitterImpl.C</A>). </FONT></I>
		</P>
		<LI><P STYLE="margin-bottom: 0in"><I><FONT SIZE=2>The listener
		beans can be either a PortableServer servant that supports
		DDS::DataReaderListener (e.g. inherits the
		POA_DDS::DataReaderListener), or a local or remote CORBA object
		reference that can be narrowed to DDS::DataReaderListener. In the
		demo DDS implementation comes with this example, all DDS interfaces
		are local, therefore, a listener implementation can simply inherit
		and implement the DDS::DataListener local stub directly (see
		example </FONT></I><A HREF="ListenerImpl.h"><I><FONT SIZE=2>ListenerImpl.h</FONT></I></A>
		<I><FONT SIZE=2>and <A HREF="ListenerImpl.C">ListenerImpl.C</A>) </FONT></I>
		</P>
	</UL>
</UL>
<OL START=3>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=3><I><B>Declaring the
	following DDS and/or application entities (beans) in XML files</B> </I></FONT>
	</P>
	<P STYLE="margin-bottom: 0in"><I><FONT SIZE=2>(see examples
	</FONT></I><A HREF="reader.xml"><I><FONT SIZE=2>reader.xml</FONT></I></A>
	<I><FONT SIZE=2>and </FONT></I><A HREF="writer.xml"><I><FONT SIZE=2>writer.xml</FONT></I></A><I><FONT SIZE=2>):</FONT></I></P>
</OL>
<UL>
	<UL>
		<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>DDS participants
		(with domain id), </I></FONT>
		</P>
		<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>topics (name and
		type Id), </I></FONT>
		</P>
		<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>subscribers (this
		is optional. if the default subscriber QoS is sufficient, the
		implicit subscriber can be used), </I></FONT>
		</P>
		<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>publishers (this
		is optional. if the default publisher QoS is sufficient, the
		implicit publisher can be used), </I></FONT>
		</P>
		<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>readers (with
		given listener), and writers (and emitter bean(s) to inject these
		writers).</I></FONT></P>
		<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>writer beans for
		container to inject the associated DDS data writer.</I></FONT></P>
	</UL>
</UL>
<OL>
	<P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>Developers only need
	to declare “<B>what</B>” is the application structure, namely
	which listener/writer beans should read/write which topics, instead
	of imperatively specifying &quot;<B>how</B>&quot; to set it up.</I></FONT></P>
</OL>
<OL START=4>
	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=3><I><B>Deploying the
	application in PocoCapsule<FONT SIZE=2>.</FONT></B> </I></FONT>
	</P>
	<P STYLE="margin-bottom: 0in"><FONT SIZE=2><I>This will activate
	declared beans and deploy them to the underlying OMG DDS based on
	“<B>what</B>” is described. </I></FONT>
	</P>
</OL>
<H3>Source Files</H3>
<P STYLE="margin-bottom: 0in"><A HREF="MyDataTypeDefs.idl">MyDataTypeDefs.idl:</A>
This IDL file defines IDL structs, and declares them as DDS types (if
the demo DDS is used)<B>.</B> 
</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in"><FONT FACE="DejaVu Sans, sans-serif"><FONT SIZE=2>Two
	IDL structs are declared, Foo and Bar.</FONT></FONT></P>
	<LI><P STYLE="margin-bottom: 0in; font-weight: medium"><FONT FACE="DejaVu Sans, sans-serif"><FONT SIZE=2>These
	two IDL structs are further declared as DDS types using the
	DDS_TYPE() macro, if the demo DDS implementation is used. </FONT></FONT>
	</P>
</UL>
<P STYLE="margin-bottom: 0in"><A HREF="MyDataTypeImpls.h">MyDataTypeImpls.h:</A>
This header provides implementations of the above declared DDS types.
 
</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in"><FONT FACE="DejaVu Sans, sans-serif"><FONT SIZE=2>Implementations
	of two declared DDS structs are generated using the<SPAN STYLE="font-weight: medium">
	DDS_TYPE() macro, if the demo DDS implementation is used.</SPAN></FONT></FONT></P>
</UL>
<P STYLE="margin-bottom: 0in"><A HREF="EmitterImpl.h">EmitterImpl.h</A>
and <A HREF="EmitterImpl.C">EmitterImpl.C:</A> They provide the
implementation of an data emitter class, the MyDataWriterEmitterImpl.
This class is simply a plain old C++ object without any super class.
Two arbitrary member functions are defined on this class for the
container to inject DDS data writer(s). On receiving an injected data
writer, these member write narrow them down to the user specified DDS
type writers and write 20 DDS data out. 
</P>
<P STYLE="margin-bottom: 0in"><A HREF="ListenerImpl.h">ListenerImpl.h</A>
and <A HREF="ListenerImpl.C">ListenerImpl.C</A>: They provide the
implementation of two data reader listener classes, the
MyFooDataReaderListenerImpl and MyBarDataReaderListenerImpl. As the
demo DDS simplifies all DDS interface to CORBA local interfaces,
these implementation classes are simply implemented by inheriting the
DDS::DataReaderListener local stub. When data are available for
reading, the underlying DDS will callback the on_data_available()
method of these implementations and inject DDS data reader
references. These listeners will narrow the injected reference down
to the user specified DDS type reader (FooDataReader or
BarDataReader) and read all queued DDS data in a loop.</P>
<P STYLE="margin-bottom: 0in"><A HREF="writer.xml">writer.xml:</A>
This is the deployment descriptor of the DDS data writer application.
Two data writers are declared, one under the implicit publisher and
another under an explicit publisher. An emitter bean is declared to
be instantiated as eager singleton, and has the above two writer
references injected in post-instantiation IoC methods. 
</P>
<P STYLE="margin-bottom: 0in"><FONT SIZE=2><A HREF="reader.xml"><FONT SIZE=3>reader.xml:</FONT></A>
<FONT SIZE=3>This is the deployment descriptor of the DDS data reader
application. Two data readers are declared, to demonstrate declaring
a data readers under implicit as well as explicit subscribers. </FONT></FONT>
</P>
<P STYLE="margin-bottom: 0in"><A HREF="writer.C">writer.C:</A> This
is a simple container, used to deploy the DDS data write application
declared in the <A HREF="writer.xml">writer.xml</A>. 
</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in; font-weight: medium"><FONT FACE="Nimbus Roman No9 L"><FONT SIZE=2>Because
	the demo DDS implementation is built on top of OMG Notification
	service, one must pass the service's IOR or URL to the deployment
	environment as follows (also see “<I>Running this example”</I>
	section):</FONT></FONT></P>
	<P STYLE="margin-bottom: 0in"><FONT FACE="Courier 10 Pitch"><FONT SIZE=2>-ORBInitRef
	NotificationService=&lt;ior or url of the service&gt;</FONT></FONT></P>
</UL>
<P STYLE="margin-bottom: 0in"><A HREF="reader.C">reader.C:</A> This
is a simple container, used to deploy the DDS data read application
declared in the <A HREF="reader.xml">reader.xml</A>. 
</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in; font-weight: medium"><FONT FACE="Nimbus Roman No9 L"><FONT SIZE=2>Because
	the demo DDS implementation is built on top of OMG Notification
	service, one must pass the service's IOR or URL to the deployment
	environment as follows (also see “<I>Running this example”</I>
	section):</FONT></FONT></P>
</UL>
<UL>
	<P STYLE="margin-bottom: 0in"><FONT FACE="Nimbus Roman No9 L"><FONT SIZE=2><FONT FACE="Courier 10 Pitch">-ORBInitRef
	NotificationService=&lt;ior or url of the service&gt;</FONT> </FONT></FONT>
	</P>
</UL>
<P STYLE="margin-bottom: 0in"><FONT SIZE=2><FONT FACE="Nimbus Roman No9 L"><A HREF="pocodds"><FONT SIZE=3><FONT FACE="DejaVu Sans, sans-serif">pocodds:</FONT></FONT></A>
<FONT SIZE=3><FONT FACE="DejaVu Sans, sans-serif">This directory
contains a small, simple, functionally limited DDS implementation
that, for minimizing the effort, is built on top of existing OMG
notification service. <FONT SIZE=3><FONT FACE="DejaVu Sans, sans-serif">PocoCapsule/CORBA-DDS
<B>does not</B> couple with or rely on this demo DDS at all. It, as
well as this example, are designed to be able to work with other DDS
implementations. </FONT></FONT>The purpose of this small demo DDS
implementation is merely for the convenience of being able to <FONT SIZE=3><FONT FACE="DejaVu Sans, sans-serif">play
this example right <FONT SIZE=3><FONT FACE="DejaVu Sans, sans-serif">out-of-the-box
without </FONT></FONT></FONT></FONT>the complexity of obtaining,
installing, and setting up a full blown DDS, as most ORBs come with
their own notification service in-box, but rare come with DDS. </FONT></FONT></FONT></FONT>
</P>
<H3>Building this example</H3>
<P STYLE="font-weight: medium">To build this example, the environment
variable POCOCAPSULE_DIR should point to the PocoCapsule/C++
installed directory. Also, this example assumes an underneath ORB
(e.g. VisiBroker/C++, TAO, etc.) is installed and its runtime and
development environment (such as POCOCAPSULE_DIR, VBROKER_DIR or
TAO_ROOT, etc. env variable) are set according to its product
specification. Then, this example can be built by simply invoking
gmake/make on linux/unix or nmake on windows. 
</P>
<H3>Running this example</H3>
<P><B><FONT FACE="Symbol">&middot; </FONT><FONT FACE="Times New Roman">Before
playing this example</FONT></B><FONT FACE="Times New Roman">, make
sure the LD_LIBRARY_PATH (on linux and solaris) or the PATH (on
windows) environment variable is set correctly to include the
${POCOCAPSULE_DIR}/lib directory and the ${VBROKREDIR}/lib (if
VisiBroker is used) or the ${TAO_ROOT}/lib directory (if TAO is
used).</FONT></P>
<P><B><FONT FACE="Symbol">&middot; </FONT><FONT FACE="Times New Roman">Start
the DDS service. </FONT></B><FONT FACE="Times New Roman">This is DDS
implementation dependent. Typically a stand-alone server should be
started. The small demo DDS comes with this example simply uses any
OMG structured event service as the underlying mechanism to perform
DDS data publish/subscribe. Therefore, to play the example with this
demo DDS, one only needs to start a notification service server, for
instance, VisiNotify, TAO or JacORB's and get and pass the service
URL or IOR to the reader and writer applications. Typically, the URLs
of the above structured event service have the following corbaloc
format:</FONT></P>
<PRE STYLE="margin-left: 0.79in; margin-bottom: 0.2in"><FONT FACE="Courier 10 Pitch">corbaloc::&lt;host&gt;:&lt;port&gt;/NotificationService</FONT></PRE><P>
<FONT FACE="Times New Roman">Here, the &lt;host&gt; is the domain
name or the dotted IP address of the Notification service server
host. </FONT>
</P>
<P><FONT FACE="Times New Roman">For instance, the VisiNotify's
default service port is 14100. JacORB server port by default is
chosen automatically from dynamic port range. User can also specify a
desired port number with -port &lt;port&gt; command line option. On
successful startup, JacORB notification server prints out the service
URL.</FONT></P>
<P><FONT FACE="Symbol">&middot; </FONT><FONT FACE="Times New Roman"><B>Start
the data reader(s) as</B>:</FONT></P>
<PRE STYLE="margin-left: 0.79in; margin-bottom: 0.2in"><FONT FACE="Courier 10 Pitch"><B>prompt&gt;</B>  reader -ORBInitRef NotificationService=&lt;service URL or IOR&gt;</FONT></PRE><P>
<FONT FACE="Times New Roman">Here, the -ORBInitRef option and the
format of the corbaloc URL are all specified in OMG CORBA and
Notification Service standard. Multiple data readers can be started
in order to observer data multi-casting. </FONT>
</P>
<P><B><FONT FACE="Symbol">&middot; </FONT><FONT FACE="Times New Roman">Start
the data writer(s) as<FONT FACE="Times New Roman">:</FONT></FONT></B></P>
<PRE STYLE="margin-left: 0.79in; margin-bottom: 0.2in"><FONT FACE="Courier 10 Pitch"><B>prompt&gt;</B>  writer -ORBInitRef NotificationService=&lt;service URL or IOR&gt;</FONT></PRE><P STYLE="font-weight: medium">
<FONT FACE="Times New Roman">Here, the -ORBInitRef option and the
format of the corbaloc URL are all specified in OMG CORBA and
Notification Service standard. </FONT>
</P>
<P STYLE="font-weight: medium">On successful connection, a writer
application will write 20 data values of type Foo, and 20 data values
of type Bar. On receiving these 40 DDS data values, the data reader
application will print out the contents of these Foo or Bar data
values.</P>
<P><A HREF="../../README.html">Back to the root page</A></P>
</BODY>
</HTML>
